livecodefandomcom-20200223-history
StyledText
Specifies the contents of a field, with its text formatting represented as LiveCode styled text array.Syntax: set the styledText of to Examples: set the styledText of field "White Paper" to tStyledTextArray set the styledText of field "Dest" to the styledText of field "Source" Use the styledText property to access and programatically manipulate the styled contents of a field. The styledText property is similar to RTFText and htmlText in that it provides a script-processable representation of the field's styled content. It differs from these two formats in two ways: 1) It is a fully faithful representation (set the styledText of field to the styledText of field results in no change to the field). 2) It is array-based. The styledText property returns a numerically-indexed array of paragraphs, each index representing each paragraph in the field in order: * tStyledTextArray1 = * ... * tStyledTextArray[] = Each paragraph array has up to two keys: * tParagraphArray"style" = * tParagraphArray"runs" = The style array contains the values for each of the paragraph styles set on that paragraph. The list of styles that are supported are: * textAlign, * listStyle, * listDepth, * listIndent, * firstIndent, * leftIndent, * rightIndent, * spaceAbove, * spaceBelow, * tabStops, * tabAlign * backgroundColor, * borderWidth, * borderColor, * hGrid, * vGrid, * dontWrap, * padding. The paragraph content array is a numerically-indexed array of runs, each index representing each run in the paragraph in order: * tParagraphContentArray1 = * ... * tParagraphContentArray[] = Each paragraph run array has up to three keys: * tRunArray"style" = * tRunArray"metadata" = * tRunArray(or "unicodeText") = The style array contains the values for each of the characters styles set on that run. The list of styles that are supported are: * textFont, * textSize, * textStyle, * textShift, * textColor, * backgroundColor, * linkText, * imageSource. * UnicodeText * Text If a run has Unicode text in it then the run array has a "unicodeText" key containing its content encoded as UTF-16. Otherwise, the run array has a "text" key containing its content encoded in the native text encoding. For example, take the following content consisting of two paragraphs: Hello World Hello, this is another line This would transpire as the following array temp: put the styledText of field 1 into temp * temp1styletextAlign = "center" * temp1runs1text = "Hello world" * temp1runs1StyletextStyle = "bold" * temp2runs1StyletextColor ="255,0,0" * temp2runs1text="Hello, this is another line" When setting the styledText property, the engine uses a very permissive algorithm to parse the arrays as follows: parseStyledTextArray pStyledText repeat for each element tEntry of pStyledText if tEntry is a sequence then parseStyledTextArray tEntry else if tEntry has key runs then begin paragraph with style tEntrystyle parseStyledTextRunArray tEntryruns end paragraph else if tEntry is an array then append tEntrytext with style tEntrystyle ... parseStyledTextRunArray pRun repeat for each element tRun in pRuns if tRun is a sequence then parseStyledTextRunArray tRun else append tRuntext with style tEntrystyle ... The engine flattens any nested numeric arrays within the tree; then iterates through the result ignoring any empty entries. If an array has a 'runs' key it is treated as an independent paragraph; otherwise it is assumed to be a 'run' and the styled text it contains is appended to the current paragraph. Note that the 'text' field of a run can contain newlines the presence of which cause paragraph breaks at the appropriate points - if such a break is made, the paragraph attributes are copied across the break. Parameters: *field: The reference to the field. *styledArray (array): An array containing the styled text. (Must be correctly constructed as aLiveCode styledText array, see comments) * The result:The engine flattens any nested numeric arrays within the tree; theniterates through the result ignoring any empty entries. If an array hasa 'runs' key it is treated as an independent paragraph; otherwise it isassumed to be a 'run' and the styled text it contains is appended to thecurrent paragraph. Note that the 'text' field of a run can containnewlines the presence of which cause paragraph breaks at the appropriatepoints - if such a break is made, the paragraph attributes are copiedacross the break. *Value: The styledText property returns a numerically-indexed array ofparagraphs. See also: textShift (property),metadata (property),textFont (property),RTFText (property),textStyle (property), Category: text processing